home *** CD-ROM | disk | FTP | other *** search
/ Chip 1996 November / Chip 11-96.iso / workshop / howto / keystrok < prev    next >
Text File  |  1996-05-25  |  8KB  |  239 lines
  1.  
  2.             Linux Keystroke HOWTO
  3.                      by
  4.          Zenon Fortuna (zenon@netcom.com)
  5.  
  6.  
  7. Version: 1.0                        May 7th '94
  8.  
  9. INDEX
  10.     0.    What is "Keystroke-HOWTO" ?
  11.     1.    Short description
  12.     2.    Tools for keyboard driver modification
  13.     3.    Modifying keytable file
  14.     3.0    Example of keytable file modification
  15.     3.1    Temporary modification of the keyboard setup
  16.     3.2    Permanent modification
  17.     4.    Example of the key_macro script
  18.     5.    Comments
  19.     6.    Further ideas ?
  20.  
  21. ----------------------------------------------------------------------------
  22.  0.    What is "Keystroke-HOWTO" ?
  23.  
  24.     This document is for users, who want to assign special action to some
  25.     of keys of the keyboard. The suggested method is to use the loadkeys(1)
  26.     or to modify the defkeymap.c file and relink the kernel.
  27.  
  28.     The method described below was tested on Linux 1.0 release, packaged
  29.     in the Slackware 1.2.0.x distribution.
  30.  
  31.  
  32. 1.    Short description
  33.  
  34.     The Linux virtual terminal and keyboard drivers assume default keyboard
  35.     mapping as defined in the drivers/char/defkeymap.c file of the kernel
  36.     source. The 12 PC keyboard function keys may get strings assigned to
  37.     their action. After pressing any of those function keys, perhaps
  38.     modified with the Alt or Ctrl keys, the current virtual terminal
  39.     adds the specific string to its input and output buffers, in effect
  40.     emulating entry of this string as typed in from the keyboard.
  41.  
  42.     Setting an appropriate string for chosen function key, we can simplify
  43.     execution of selected command, for example calling a Shell-script
  44.     "/usr/local/bin/key_macro", which we can create and modify as desired.
  45.  
  46.  
  47. 2.    Tools for keyboard driver modification
  48.  
  49.     We may use loadkeys(1), dumpkeys(1) and showkey(1):
  50.       The loadkeys(1) utility helps to load new strings into the kernel
  51.     keyboard buffers or prepares the new C-code to modify the kernel.
  52.       The dumpkeys(1) should be used to get the current keyboard mapping
  53.     table for inspection or modification.
  54.       The showkey(1) may assist us to obtain the keycode of the selected
  55.     function key.
  56.  
  57.     If your Linux system does not have these utilities, you may get them
  58.     via anonymouse ftp as kbd-0.87.tar.gz package from
  59.         sunsite.unc.edu:/pub/Linux/system/Keyboards, or
  60.         tsx-11.mit.edu:/pub/linux/sources/system
  61.  
  62.  
  63. 3.    Modifying keytable file
  64.  
  65.     Linux kernel includes compiled defkeymap.c code, which is generated
  66.     with the loadkeys(1) utility from a defkeymap.map file. Both files
  67.     are included in the src/linux/drivers/char directory.
  68.  
  69.     We need to modify the defkeymap.map file, so let's make a local
  70.     copy of it either by
  71.         # cp defkeymap.map my_keytable.map
  72.     or
  73.         # dumpkeys > my_keytable.map
  74.  
  75.     There is also a large collection of different keytable files in the
  76.     /usr/lib/kbd/keytables directory, from which "defkeym.map" is identical
  77.     to the src/linux/drivers/char/defkeymap.map file.
  78.  
  79.     The method which uses the dumpkeys(1) utility is recommended, because
  80.     it may happen, that our kernel was already modified or generated
  81.     for us with different defkeymap.map file than the one we can find.
  82.  
  83.     Lets read the contents of our my_keytable.map file: there are more
  84.     than 300 lines of code, and we can find 3 groups of declarations.
  85.     The first group begins with words "keycode" or "alt keycode" or
  86.     "control keycode" or "shift keycode".
  87.     The second group begins with the word "string".
  88.     The third group begins with the word "compose".
  89.  
  90.     More about the keytables(5) syntax can be read with
  91.         % man keytables
  92.  
  93.  
  94. 3.0    Example of keytable file modification
  95.  
  96.     As an example of assigning a macro-string to a function key stroke,
  97.     let's make the "Ctrl-F1" to call our "/usr/local/bin/key_macro"
  98.     Shell-script.
  99.  
  100.     First of all we should find out what is the keycode for the F1 function
  101.     key.
  102.     We may use the showkey(1) utility to find the keycode with pressing F1.
  103.  
  104.     Instead we can search for the "F1" string in the "my_keytable.map" file
  105.     to find the following line:
  106.  
  107.     keycode  59 = F1               F11              Console_13      
  108.  
  109.     This means, that the keycode for the F1 function key is 59.
  110.     This line defines also, that after pressing the F1 key the keyboard
  111.     driver would send out the string denoted by the string-code "F1".
  112.     To see the contents of this string, one can search for the "string F1"
  113.     pattern, to find
  114.  
  115.     string F1 = "\033[[A"
  116.  
  117.     This means, that after pressing the F1 key, the keyboard driver sends
  118.     the "Esc [ [ A" (without blank spaces).
  119.  
  120.     We shouldn't change this string, because some applications depend on
  121.     this string as default action of the F1 function key.
  122.  
  123.     However, below the "keycode  59 =..." line we may read a line defining
  124.     the Ctrl-F1 action:
  125.  
  126.     control keycode  59 = F1
  127.  
  128.     This essentially means, that pressing "Ctrl-F1" we send the same string
  129.     out (denoted by the string-code F1) as pressing the plain "F1" key.
  130.     To change it we should find an unused string-code name.
  131.  
  132.     A good candidate could be the F26 string-code, which in the default
  133.     defkeymap.map file denotes an empty string in the following line:
  134.  
  135.     F26 = ""
  136.  
  137.     Instead, let's change it in "my_keytable.map" to
  138.  
  139.     F26 = "/usr/local/bin/key_macro\n"
  140.  
  141.     Then let's change the shown above line defining Ctrl-F1 action, to
  142.  
  143.     control keycode 59 = F26
  144.  
  145.     In the summary, we made two changes to the original "my_keytable.map"
  146.     file: we declared the new value to the F26 string and we have defined
  147.     the Ctrl-F1 calling the F26 string.
  148.  
  149.  
  150. 3.1    Temporary modification of the keyboard setup
  151.  
  152.     Having properly modified "my_keytable.map" we can copy the changes
  153.     to the kernel keyboard driver, using the loadkeys(1) utility:
  154.  
  155.     % loadkeys my_keytable.map
  156.  
  157.     The permission to modify the kernel keyboard driver is granted to
  158.     everybody who has the read access to the "/dev/console" device.
  159.  
  160.     To verify that the intended changes were installed, we can use the
  161.     dumpkeys(1) utility to check the F26 value, for example
  162.  
  163.     % dumpkeys | grep F26
  164.  
  165.     We may see:
  166.     string F26 = "/usr/local/bin/key_macro\012"
  167.  
  168.     which is OK, because "\012", or LF, is equivalent to "\n".
  169.  
  170.     Now, pressing "Ctrl-F1" should call the "/usr/local/bin/key_macro"
  171.     Shell-script, as intended. 
  172.  
  173.  
  174. 3.2    Permanent modification
  175.  
  176.     The changes to the kernel keyboard driver imposed by the loadkeys(1)
  177.     last until the next reboot (or the next call to loadkeys).
  178.  
  179.     We can modify the /etc/rc.d/rc.local to call the loadkeys with our
  180.     my_keytable.map file as an argument. Instead, we can modify the
  181.     src/linux/drivers/char/defkeymap.c and re-link the kernel with
  182.     new defaults.
  183.  
  184.     We should not modify the defkeymap.c manually, but rather generate
  185.     it with the loadkeys(1) utility:
  186.  
  187.     # mv defkeymap.c defkeymap.c.ORIG
  188.     # loadkeys --mktable my_keytable.map > defkeymap.c
  189.  
  190.     Then we should generate the new kernel, essentially changing directory
  191.     to the root of the linux kernel source, and using the make(1).
  192.  
  193.     Finally, we should use the lilo(1) to boot with our new kernel.
  194.  
  195.  
  196. 4.    Example of the key_macro script
  197.  
  198.     A particularly useful script for simple-key-stroke operation may be
  199.     a Shell-script preparing, or printing, a screen dump.
  200.     The code below should be regarded as an example of possible
  201.     applications:
  202.  
  203. #!/bin/sh
  204. #
  205. # This is an example of useful key_macro script
  206. #
  207.  
  208. VT_NUMBER=`tty|cut -c9-`
  209. FILE=/tmp/vt$VT_NUMBER.dump
  210. setterm -dump $VT_NUMBER -file $FILE
  211. echo SCREEN DUMP saved in $FILE
  212. #
  213. # Uncomment the line below if you want to print the resulted dump-file
  214. # lpr $FILE
  215.  
  216.     The *problem* with the above "setterm -dump ..." call is, that
  217.     it uses the ioctl(0,TIOCLINUX) system call, which is reserved
  218.     for the Superuser only. This means, that the intended screen-dump
  219.     would work only for "root". Oh, well.
  220.  
  221.  
  222. 5.    Comments
  223.  
  224.     There is a limit to the sum the lengths of all strings which are
  225.     to be copied to the keyboard driver: FUNC_BUFSIZE, declared in
  226.     the "keyboard.h" is set to 512 bytes.
  227.  
  228.     In case of attempt to assign too long strings, the loadkeys(1)
  229.     will fail with the message: "func-buf overflow".
  230.  
  231.     The defkeymap.map and generated getkeymap.c use about 100 bytes only.
  232.  
  233.  
  234. 6.    Further ideas ?
  235.  
  236.     In case you find anything worth adding to this document, please send
  237.     your comments to zenon@netcom.com -- thanks (zf)
  238.  
  239.